﻿<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
  
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <title>Items by Name </title>
    <meta name="viewport" content="width=device-width">
    <meta name="title" content="Items by Name ">
    <meta name="generator" content="docfx 2.59.2.0">
    
    <link rel="shortcut icon" href="../../favicon.ico">
    <link rel="stylesheet" href="../../styles/docfx.vendor.css">
    <link rel="stylesheet" href="../../styles/docfx.css">
    <link rel="stylesheet" href="../../styles/main.css">
    <link rel="stylesheet" href="../../styles/socialbar.css">
    <link rel="stylesheet" href="../../styles/header.css">
    <link rel="stylesheet" href="../../styles/version.css">
    <link href="https://fonts.googleapis.com/css?family=Roboto:400,100,300,500,700,100italic,300italic,400italic" rel="stylesheet" type="text/css">
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
    <meta property="docfx:navrel" content="../../toc.html">
    <meta property="docfx:tocrel" content="../toc.html">
    <meta property="docfx:uid" content="doc-restapi-Items-by-Name">
    
    <meta property="docfx:rel" content="../../">
    
    <script type="text/javascript" src="../../nav.js"></script>
    <script type="text/javascript" src="../toc.js"></script>
  
  </head>  <body data-spy="scroll" data-target="#affix" data-offset="120">
    <div id="wrapper">
      <header>
        
        <div class="mb-socials-heading" style="height: 40px;">
        	<div class="mb-socials-heading-inner container">
        		<div class="mb-socials-heading-right">
        			<div class="mb-socials-list">
                          
        				<div class="mb-socials-item facebook">
        					<a class="mb-socials-item-link" target="_blank" href="https://facebook.com/embyapp"></a>
        					<div class="mb-socials-item-popup">
        						<span>Facebook</span>
        					</div>
        				</div><div class="mb-socials-item twitter">
        					<a class="mb-socials-item-link" target="_blank" href="https://twitter.com/embyapp"></a>
        					<div class="mb-socials-item-popup">
        						<span>Twitter</span>
        					</div>
        				</div>
        				<div class="mb-socials-item pinterest">
        					<a class="mb-socials-item-link" target="_blank" href="https://www.pinterest.com/emby0240/emby-news/"></a>
        					<div class="mb-socials-item-popup">
        						<span>Pinterest</span>
        					</div>
        				</div>
        				<div class="mb-socials-item tumblr">
        					<a class="mb-socials-item-link" target="_blank" href="https://embyapp.tumblr.com/"></a>
        					<div class="mb-socials-item-popup">
        						<span>Tumblr</span>
        					</div>
        				</div>
        				<div class="mb-socials-item github">
        					<a class="mb-socials-item-link" target="_blank" href="https://github.com/MediaBrowser"></a>
        					<div class="mb-socials-item-popup">
        						<span>GitHub</span>
        					</div>
        				</div><div class="mb-socials-item rss">
        					<a class="mb-socials-item-link" target="_blank" href="https://emby.media/blog.xml"></a>
        					<div class="mb-socials-item-popup">
        						<span>RSS</span>
        					</div>
        				</div>
                          
        			</div>
        		</div>
        	</div>
        </div>
        <div class="container">
        	<nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
        		  
        		  <a class="navbar-brand" href="../../index.html">
        		    <img id="logo" class="svg" src="../../images/emby_dev_logo.png" alt="">
        		  </a>
        		  <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
        			<span class="sr-only">Toggle navigation</span>
        			<span class="icon-bar"></span>
        			<span class="icon-bar"></span>
        			<span class="icon-bar"></span>
        		  </button>
        		<div class="collapse navbar-collapse" id="navbar">
        			
        			<ul class="nav level1 navbar-nav">
        			      <li class="nav-item">
        			          <a class="nav-link" href="../../index.html" title="DEV Home">DEV Home</a>
        			      </li>
        			      <li class="nav-item">
        			          <a class="nav-link" href="../../doc/index.html" title="Documentation">Documentation</a>
        			      </li>
        			      <li class="nav-item">
        			          <a class="nav-link" href="../../reference/index.html" title="Reference">Reference</a>
        			      </li>
        			      <li class="nav-item">
        			          <a class="nav-link" href="../../download/index.html" title="Download">Download</a>
        			      </li>
        			</ul>		</div>
        	</nav>
        </div>
        <div class="nav-overlay d-none"></div>        
        <div class="subnav navbar navbar-default">
          <div class="container">
            <div class="hide-when-search" id="breadcrumb">
        	  <ul class="breadcrumb">
        		<li></li>
        	  </ul>
        	</div>
        
        	<div class="breadcrumpsearch">
        	  <form class="navbar-form navbar-right" role="search" id="search">
        		<div class="form-group">
        		  <input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
        		</div>
        	  </form>
        	</div>
          </div>
        </div>
      </header>
      <div class="container body-content">
        
        <div id="search-results">
          <div class="search-list">Search Results for <span></span></div>
          <div class="sr-items">
            <p><i class="glyphicon glyphicon-refresh index-loading"></i></p>
          </div>
          <ul id="pagination" data-first="First" data-prev="Previous" data-next="Next" data-last="Last"></ul>
        </div>
      </div>
      <div role="main" class="container body-content hide-when-search">
        
        <div class="sidenav hide-when-search">
          <a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
          <div class="sidetoggle collapse" id="sidetoggle">
            <div id="sidetoc"></div>
          </div>
        </div>
        <div class="article row grid-right">
          <div class="col-md-10">
            <article class="content wrap" id="_content" data-uid="doc-restapi-Items-by-Name">
<h1 id="items-by-name">Items by Name</h1>

<p>Media items will contain lists of related items, such as Artists, Genres, Persons and Studios. These related items are referred to as &quot;items by name&quot; and can be retrieved by their name. The endpoints to retrieve a <strong>single item by name</strong> are:</p>
<ul>
<li><p><a class="xref" href="../../reference/RestAPI/ArtistsService/getArtistsByName.html">/Artists/{Name}</a></p>
</li>
<li><p><a class="xref" href="../../reference/RestAPI/GenresService/getGenresByName.html">/Genres/{Name}</a></p>
</li>
<li><p><a class="xref" href="../../reference/RestAPI/GameGenresService/getGamegenresByName.html">/GameGenres/{Name}</a></p>
</li>
<li><p><a class="xref" href="../../reference/RestAPI/MusicGenresService/getMusicgenresByName.html">/MusicGenres/{Name}</a></p>
</li>
</ul>
<div class="NOTE">
<h5>Note</h5>
<p>All '?', '&amp;' and '/' characters must be replaced by dashes '-'</p>
</div>
<p>For example, you have an audio file with Akon as the artist. You want to allow the user to click on Akon and see artist information. To do this, use the following:</p>
<pre><code class="lang-restApi">/Artists/Akon?userId=xxx
</code></pre>
<p>This will return an item with identical structure to normal library items. UserId is optional, and if included, will include user data such as like/dislike/favorite statuses. These item can also have images.</p>
<h2 id="images">Images</h2>
<p>Images can be retrieved in the same fashion as media items using the object Id's.</p>
<h2 id="querying-for-items-by-name">Querying for items by name</h2>
<p>In addition to individual retrieval, there are querying endpoints that will return lists of these items.</p>
<ul>
<li><p><a class="xref" href="../../reference/RestAPI/ArtistsService/getArtists.html">/Artists</a></p>
</li>
<li><p><a class="xref" href="../../reference/RestAPI/ArtistsService/getArtistsAlbumartists.html">/Artists/AlbumArtists</a></p>
</li>
<li><p><a class="xref" href="../../reference/RestAPI/GameGenresService/getGamegenres.html">/GameGenres</a></p>
</li>
<li><p><a class="xref" href="../../reference/RestAPI/GenresService/getGenres.html">/Genres</a></p>
</li>
<li><p><a class="xref" href="../../reference/RestAPI/MusicGenresService/getMusicgenres.html">/MusicGenres</a></p>
</li>
<li><p><a class="xref" href="../../reference/RestAPI/PersonsService/getPersons.html">/Persons</a></p>
</li>
<li><p><a class="xref" href="../../reference/RestAPI/StudiosService/getStudios.html">/Studios</a></p>
</li>
</ul>
<p>These can be retrieved from the entire library, or limited to a specific folder, or limited to specific item types. For example, the following query will return all movie genres within a user's library:</p>
<pre><code class="lang-restApi">/Genres?IncludeItemTypes=Movie&amp;Recursive=true&amp;userId=xxx
</code></pre>
<p>As with media item querying, these endpoints also support <strong>paging</strong>, <strong>filtering</strong>, <strong>sorting</strong> and <strong>configurable output fields</strong>. See the build-in documentation for details.</p>
<h2 id="item-counts">Item Counts</h2>
<p>Each artist, genre, studio, person, etc, will have the following additional properties available, to indicate how many items in the library they apply to:</p>
<ul>
<li>TotalCount</li>
<li>AdultVideoCount</li>
<li>MovieCount</li>
<li>SeriesCount</li>
<li>EpisodeCount</li>
<li>GameCount</li>
<li>TrailerCount</li>
<li>SongCount</li>
<li>AlbumCount</li>
<li>MusicVideoCount</li>
</ul>
</article>
          </div>
          
          <div class="hidden-sm col-md-2" role="complementary">
            <div class="sideaffix">
              <div class="contribution">
                <ul class="nav">
                </ul>
              </div>
              <div class="sdkversion Release">
                  SDK <span class="sdkVersionSpan"></span>
              </div>
              <nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
                <h5>On this Page</h5>
                <div></div>
              </nav>
            </div>
          </div>
        </div>
      </div>
      
      <footer>
        <div class="grad-bottom"></div>
        <div class="footer">
          <div class="container">
            <span class="pull-right">
              <a href="#top">Back to Top</a>
            </span>
            Copyright 2022 © EMBY LLC.  Please see our <a class="lnk" href="https://emby.media/terms.html">terms of use</a> and <a class="lnk" href="https://emby.media/privacy.html">privacy policy</a>.
            
          </div>
        </div>
      </footer>
    </div>
    
    <script type="text/javascript" src="../../styles/docfx.vendor.js"></script>
    <script type="text/javascript" src="../../searchIndex.js"></script>
    <script type="text/javascript" src="../../styles/lunr.min.js"></script>
    <script type="text/javascript" src="../../styles/docfx.js"></script>
    <script type="text/javascript" src="../../styles/main.js"></script>
  </body>
</html>
